home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / Sound / AHI / Developer / docs / ahi_sub.doc next >
Text File  |  1997-11-04  |  23KB  |  670 lines
  1. TABLE OF CONTENTS
  2. 0001 [driver].audio/--background--
  3. 0002 [driver].audio/AHIsub_#?
  4. 0003 [driver].audio/AHIsub_AllocAudio
  5. 0004 [driver].audio/AHIsub_Disable
  6. 0005 [driver].audio/AHIsub_Enable
  7. 0006 [driver].audio/AHIsub_FreeAudio
  8. 0007 [driver].audio/AHIsub_GetAttr
  9. 0008 [driver].audio/AHIsub_HardwareControl
  10. 0009 [driver].audio/AHIsub_Start
  11. 0010 [driver].audio/AHIsub_Stop
  12. 0011 [driver].audio/AHIsub_Update
  13. [driver].audio/--background--
  14.  
  15. OVERVIEW
  16.  
  17.        DRIVER VERSIONS
  18.  
  19.        The lowest supported driver version is 2. If you use any feature
  20.        introduced in later versions of AHI, you should set the driver
  21.        version to the same version as the features were introduced with.
  22.        Example: You use PreTimer() and PostTimer(), and since these
  23.        calls were added in V4 of ahi.device, your driver's version should
  24.        be 4, too.
  25.  
  26.        AUDIO ID NUMBERS
  27.  
  28.        Just some notes about selecting ID numbers for different modes:
  29.        It is up to the driver programmer to chose which modes should be
  30.        available to the user. Take care when selecting.
  31.  
  32.        The upper word is the hardware ID, and can only be allocated by
  33.        Martin Blom <lcs@lysator.liu.se>. The lower word is free, but in
  34.        order to allow enhancements, please only use bit 0 to 3 for modes!
  35.        If your driver supports multiple sound cards, use bit 12-15 to
  36.        select card (first one is 0). If your sound card has multiple
  37.        AD/DA converters, you can use bit 8-11 to select them (the first
  38.        should be 0).
  39.  
  40.        Set the remaining bits to zero.
  41.  
  42.        Use AHI:Developer/Support/ScanAudioModes to have a look at the modes
  43.        currently available. Use AHI:Developer/Support/sift to make sure your
  44.        mode descriptor file is a legal IFF file.
  45.  
  46.        I do reserve the right to change the rules if I find them incorrect!
  47.  
  48.  
  49. [driver].audio/AHIsub_#?
  50.  
  51. NAME
  52.        AHIsub_SetEffect -- Set effect.
  53.        AHIsub_SetFreq -- Set frequency.
  54.        AHIsub_SetSound -- Set sound.
  55.        AHIsub_SetVol -- Set volume and stereo panning.
  56.        AHIsub_LoadSound -- Prepare a sound for playback.
  57.        AHIsub_UnloadSound -- Discard a sound.
  58.  
  59.  
  60. SYNOPSIS
  61.        See functions in 'ahi.device'.
  62.  
  63.  
  64. IMPLEMENTATION
  65.        If AHIsub_AllocAudio() did not return with bit AHISB_MIXING set,
  66.        all user calls to these function will be routed to the driver.
  67.  
  68.        If AHIsub_AllocAudio() did return with bit AHISB_MIXING set, the
  69.        calls will first be routed to the driver, and only handled by
  70.        'ahi.device' if the driver returned AHIS_UNKNOWN. This way it is
  71.        possible to add effects that the sound card handles on its own, like
  72.        filter and echo effects.
  73.  
  74.        For what each function does, see the autodocs for 'ahi.device'.
  75.  
  76.  
  77. INPUTS
  78.        See functions in 'ahi.device'.
  79.  
  80.  
  81. NOTES
  82.        See functions in 'ahi.device'.
  83.  
  84.  
  85. SEE ALSO
  86.        ahi.device/AHI_SetEffect(), ahi.device/AHI_SetFreq(),
  87.        ahi.device/AHI_SetSound(), ahi.device/AHI_SetVol(),
  88.        ahi.device/AHI_LoadSound(), ahi.device/AHI_UnloadSound()
  89.        
  90.  
  91.  
  92. [driver].audio/AHIsub_AllocAudio
  93.  
  94. NAME
  95.        AHIsub_AllocAudio -- Allocates and initializes the audio hardware.
  96.  
  97.  
  98. SYNOPSIS
  99.        result = AHIsub_AllocAudio( tags, audioctrl);
  100.        D0                          A1    A2
  101.  
  102.        ULONG AHIsub_AllocAudio( struct TagItem *, struct AHIAudioCtrlDrv * );
  103.  
  104.  
  105. IMPLEMENTATION
  106.        Allocate and initialize the audio hardware. Decide if and how you
  107.        wish to use the mixing routines provided by 'ahi.device', by looking
  108.        in the AHIAudioCtrlDrv structure and parsing the tag list for tags
  109.        you support.
  110.  
  111.        1) Use mixing routines with timing:
  112.            You will need to be able to play any number of samples from
  113.            about 80 up to 65535 with low overhead.
  114.            · Update AudioCtrl->ahiac_MixFreq to nearest value that your
  115.              hardware supports.
  116.            · Return AHISF_MIXING|AHISF_TIMING.
  117.        2) Use mixing routines without timing:
  118.            If the hardware can't play samples with any length, use this
  119.            alternative and provide timing yourself. The buffer must
  120.            take less than about 20 ms to play, preferable less than 10!
  121.            · Update AudioCtrl->ahiac_MixFreq to nearest value that your
  122.              hardware supports.
  123.            · Store the number of samples to mix each pass in
  124.              AudioCtrl->ahiac_BuffSamples.
  125.            · Return AHISF_MIXING
  126.            Alternatively, you can use the first method and call the
  127.            mixing hook several times in a row to fill up a buffer.
  128.            In that case, AHIsub_GetAttr(AHIDB_MaxPlaySamples) should
  129.            return the size of the buffer plus AudioCtrl->ahiac_MaxBuffSamples.
  130.            If the buffer is so large that it takes more than (approx.) 10 ms to
  131.            play it for high sample frequencies, AHIsub_GetAttr(AHIDB_Realtime)
  132.            should return FALSE.
  133.        3) Don't use mixing routines:
  134.            If your hardware can handle everything without using the CPU to
  135.            mix the channels, you tell 'ahi.device' this by not setting
  136.            either the AHISB_MIXING or the AHISB_TIMING bit.
  137.  
  138.        If you can handle stereo output from the mixing routines, also set
  139.        bit AHISB_KNOWSTEREO.
  140.  
  141.        If you can handle hifi (32 bit) output from the mixing routines,
  142.        set bit AHISB_KNOWHIFI.
  143.  
  144.        If this driver can be used to record samples, set bit AHISB_CANRECORD,
  145.        too (regardless if you use the mixing routines in AHI or not).
  146.  
  147.        If the sound card has hardware to do DSP effects, you can set the
  148.        AHISB_CANPOSTPROCESS bit. The output from the mixing routines will 
  149.        then be two separate buffers, one wet and one dry. You should then
  150.        apply the Fx on the wet buffer, and post-mix the two buffers before
  151.        you send the samples to the DAC. (V4)
  152.  
  153.  
  154. INPUTS
  155.        tags - pointer to a taglist.
  156.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  157.  
  158.  
  159. TAGS
  160.        The tags are from the audio database (AHIDB_#? in <devices/ahi.h>),
  161.        NOT the tag list the user called ahi.device/AHI_AllocAudio() with.
  162.  
  163.  
  164. RESULT
  165.        Flags, defined in <libraries/ahi_sub.h>.
  166.  
  167.  
  168. EXAMPLE
  169.  
  170.  
  171. NOTES
  172.        You don't have to clean up on failure, AHIsub_FreeAudio() will
  173.        always be called.
  174.  
  175.  
  176. BUGS
  177.  
  178.  
  179. SEE ALSO
  180.        AHIsub_FreeAudio(), AHIsub_Start()
  181.  
  182.  
  183. [driver].audio/AHIsub_Disable
  184.  
  185. NAME
  186.        AHIsub_Disable -- Temporary turn off audio interrupt/task
  187.  
  188.  
  189. SYNOPSIS
  190.        AHIsub_Disable( audioctrl );
  191.                        A2
  192.  
  193.        void AHIsub_Disable( struct AHIAudioCtrlDrv * );
  194.  
  195.  
  196. IMPLEMENTATION
  197.        If you are lazy, then call exec.library/Disable().
  198.        If you are smart, only disable your own interrupt or task.
  199.  
  200.  
  201. INPUTS
  202.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  203.  
  204.  
  205. NOTES
  206.        This call should be guaranteed to preserve all registers.
  207.        This call nests.
  208.  
  209.  
  210. SEE ALSO
  211.        AHIsub_Enable(), exec.library/Disable()
  212.  
  213.  
  214. [driver].audio/AHIsub_Enable
  215.  
  216. NAME
  217.        AHIsub_Enable -- Turn on audio interrupt/task
  218.  
  219.  
  220. SYNOPSIS
  221.        AHIsub_Enable( audioctrl );
  222.                       A2
  223.  
  224.        void AHIsub_Enable( struct AHIAudioCtrlDrv * );
  225.  
  226.  
  227. IMPLEMENTATION
  228.        If you are lazy, then call exec.library/Enable().
  229.        If you are smart, only enable your own interrupt or task.
  230.  
  231.  
  232. INPUTS
  233.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  234.  
  235.  
  236. NOTES
  237.        This call should be guaranteed to preserve all registers.
  238.        This call nests.
  239.  
  240.  
  241. SEE ALSO
  242.        AHIsub_Disable(), exec.library/Enable()
  243.  
  244.  
  245. [driver].audio/AHIsub_FreeAudio
  246.  
  247. NAME
  248.        AHIsub_FreeAudio -- Deallocates the audio hardware.
  249.  
  250.  
  251. SYNOPSIS
  252.        AHIsub_FreeAudio( audioctrl );
  253.                          A2
  254.  
  255.        void AHIsub_FreeAudio( struct AHIAudioCtrlDrv * );
  256.  
  257.  
  258. IMPLEMENTATION
  259.        Deallocate the audio hardware and other resources allocated in
  260.        AHIsub_AllocAudio(). AHIsub_Stop() will always be called by
  261.        'ahi.device' before this call is made.
  262.  
  263.  
  264. INPUTS
  265.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  266.  
  267.  
  268. NOTES
  269.        It must be safe to call this routine even if AHIsub_AllocAudio()
  270.        was never called, failed or called more than once.
  271.  
  272.  
  273. SEE ALSO
  274.        AHIsub_AllocAudio()
  275.  
  276.  
  277. [driver].audio/AHIsub_GetAttr
  278.  
  279. NAME
  280.        AHIsub_GetAttr -- Returns information about audio modes or driver
  281.  
  282.  
  283. SYNOPSIS
  284.        AHIsub_GetAttr( attribute, argument, default, taglist, audioctrl );
  285.        D0              D0         D1        D2       A1       A2
  286.  
  287.        LONG AHIsub_GetAttr( ULONG, LONG, LONG, struct TagItem *,
  288.                             struct AHIAudioCtrlDrv * );
  289.  
  290.  
  291. IMPLEMENTATION
  292.        Return the attribute based on a tag list and an AHIAudioCtrlDrv
  293.        structure, which are the same that will be passed to
  294.        AHIsub_AllocAudio() by 'ahi.device'. If the attribute is
  295.        unknown to you, return the default.
  296.  
  297.  
  298. INPUTS
  299.        attribute - Is really a Tag and can be one of the following:
  300.            AHIDB_Bits - Return how many output bits the tag list will
  301.                result in.
  302.            AHIDB_MaxChannels - Return the resulting number of channels.
  303.            AHIDB_Frequencies - Return how many mixing/sampling frequencies
  304.                you support
  305.            AHIDB_Frequency - Return the argument:th frequency
  306.                Example: You support 3 frequencies 32, 44.1 and 48 kHz.
  307.                    If argument is 1, return 44100.
  308.            AHIDB_Index - Return the index which gives the frequency closest
  309.                to argument.
  310.                Example: You support 3 frequencies 32, 44.1 and 48 kHz.
  311.                    If argument is 40000, return 1 (=> 44100).
  312.            AHIDB_Author - Return pointer to name of driver author:
  313.                "Martin 'Leviticus' Blom"
  314.            AHIDB_Copyright - Return pointer to copyright notice, including
  315.                the '©' character: "© 1996 Martin Blom" or "Public Domain"
  316.            AHIDB_Version - Return pointer version string, normal Amiga
  317.                format: "paula 1.5 (18.2.96)\r\n"
  318.            AHIDB_Annotation - Return pointer to an annotation string, which
  319.                can be several lines.
  320.            AHIDB_Record - Are you a sampler, too? Return TRUE or FALSE.
  321.            AHIDB_FullDuplex - Return TRUE or FALSE.
  322.            AHIDB_Realtime - Return TRUE or FALSE.
  323.            AHIDB_MaxPlaySamples - Normally, return the default. See
  324.                AHIsub_AllocAudio(), section 2.
  325.            AHIDB_MaxRecordSamples - Return the size of the buffer you fill
  326.                when recording.
  327.  
  328.            The following are associated with AHIsub_HardwareControl() and are
  329.            new for V2.
  330.            AHIDB_MinMonitorVolume
  331.            AHIDB_MaxMonitorVolume - Return the lower/upper limit for
  332.                AHIC_MonitorVolume. If unsupported but always 1.0, return
  333.                1.0 for both.
  334.            AHIDB_MinInputGain
  335.            AHIDB_MaxInputGain - Return the lower/upper limit for
  336.                AHIC_InputGain. If unsupported but always 1.0, return 1.0 for
  337.                both.
  338.            AHIDB_MinOutputVolume
  339.            AHIDB_MaxOutputVolume - Return the lower/upper limit for
  340.                AHIC_OutputVolume.
  341.            AHIDB_Inputs - Return how many inputs you have.
  342.            AHIDB_Input - Return a short string describing the argument:th
  343.                input. Number 0 should be the default one. Example strings
  344.                can be "Line 1", "Mic", "Optical" or whatever.
  345.            AHIDB_Outputs - Return how many outputs you have.
  346.            AHIDB_Output - Return a short string describing the argument:th
  347.                output. Number 0 should be the default one. Example strings
  348.                can be "Line 1", "Headphone", "Optical" or whatever.
  349.        argument - extra info for some attributes.
  350.        default - What you should return for unknown attributes.
  351.        taglist - Pointer to a tag list that eventually will be fed to
  352.            AHIsub_AllocAudio(), or NULL.
  353.        audioctrl - Pointer to an AHIAudioCtrlDrv structure that eventually
  354.            will be fed to AHIsub_AllocAudio(), or NULL.
  355.  
  356.  
  357. NOTES
  358.  
  359.  
  360. SEE ALSO
  361.        AHIsub_AllocAudio(), AHIsub_HardwareControl(),
  362.        ahi.device/AHI_GetAudioAttrsA()
  363.  
  364.  
  365. [driver].audio/AHIsub_HardwareControl
  366.  
  367. NAME
  368.        AHIsub_HardwareControl -- Modify sound card settings
  369.  
  370.  
  371. SYNOPSIS
  372.        AHIsub_HardwareControl( attribute,  argument, audioctrl );
  373.        D0                      D0          D1        A2
  374.  
  375.        LONG AHIsub_HardwareControl( ULONG, LONG, struct AHIAudioCtrlDrv * );
  376.  
  377.  
  378. IMPLEMENTATION
  379.        Set or return the state of a particular hardware component. AHI uses
  380.        AHIsub_GetAttr() to supply the user with limits and what tags are
  381.        available.
  382.  
  383.  
  384. INPUTS
  385.        attribute - Is really a Tag and can be one of the following:
  386.            AHIC_MonitorVolume - Set the input monitor volume to argument.
  387.            AHIC_MonitorVolume_Query - Return the current input monitor
  388.                volume (argument is ignored).
  389.  
  390.            AHIC_InputGain - Set the input gain to argument. (V2)
  391.            AHIC_InputGain_Query (V2)
  392.  
  393.            AHIC_OutputVolume - Set the output volume to argument. (V2)
  394.            AHIC_OutputVolume_Query (V2)
  395.  
  396.            AHIC_Input - Use the argument:th input source (default is 0). (V2)
  397.            AHIC_Input_Query (V2)
  398.  
  399.            AHIC_Output - Use the argument:th output destination (default
  400.                is 0). (V2)
  401.            AHIC_Output_Query (V2)
  402.  
  403.        argument - What value attribute should be set to.
  404.        audioctrl - Pointer to an AHIAudioCtrlDrv structure.
  405.  
  406.  
  407. RESULT
  408.        Return the state of selected attribute. If you were asked to set
  409.        something, return TRUE. If attribute is unknown to you or unsupported,
  410.        return FALSE.
  411.  
  412.  
  413. NOTES
  414.        This call must be safe from interrupts.
  415.  
  416.  
  417. SEE ALSO
  418.        ahi.device/AHI_ControlAudioA(), AHIsub_GetAttr()
  419.  
  420.  
  421. [driver].audio/AHIsub_Start
  422.  
  423. NAME
  424.        AHIsub_Start -- Starts playback or recording
  425.  
  426.  
  427. SYNOPSIS
  428.        error = AHIsub_Start( flags, audioctrl );
  429.        D0                    D0     A2
  430.  
  431.        ULONG AHIsub_Start(ULONG, struct AHIAudioCtrlDrv * );
  432.  
  433.  
  434. IMPLEMENTATION
  435.        What to do depends what you returned in AHIsub_AllocAudio().
  436.  
  437.      * First, assume bit AHISB_PLAY in flags is set. This means that you
  438.        should begin playback.
  439.  
  440.      - AHIsub_AllocAudio() returned AHISF_MIXING|AHISF_TIMING:
  441.  
  442.        A) Allocate a mixing buffer of ahiac_BuffSize bytes. The buffer must
  443.           be long aligned!
  444.        B) Create/start an interrupt or task that will do 1-6 over and over
  445.           again until AHIsub_Stop() is called. Note that it is not a good
  446.           idea to do the actual mixing and conversion in a real hardware
  447.           interrupt. Signal a task or create a Software Interrupt to do
  448.           the number crunching.
  449.  
  450.        1) Call the user Hook ahiac_PlayerFunc with the following parameters:
  451.                   A0 - (struct Hook *)
  452.                   A2 - (struct AHIAudioCtrlDrv *)
  453.                   A1 - Set to NULL.
  454.  
  455.        2) [Call the ahiac_PreTimer function. If it returns TRUE (Z will be
  456.           cleared so you don't have to test d0), skip step 3 and 4. This
  457.           is used to avoid overloading the CPU. This step is optional.
  458.           A2 is assumed to point to struct AHIAudioCtrlDrv. All registers
  459.           except d0 are preserved.  (V4)]
  460.  
  461.        3) Call the mixing Hook (ahiac_MixerFunc) with the following
  462.           parameters:
  463.                   A0 - (struct Hook *)           - The Hook itself
  464.                   A2 - (struct AHIAudioCtrlDrv *)
  465.                   A1 - (WORD *[])                - The mixing buffer.
  466.           Note that ahiac_MixerFunc preserves ALL registers.
  467.           The user Hook ahiac_SoundFunc will be called by the mixing
  468.           routine when a sample have been processed, so you don't have to
  469.           worry about that.
  470.           How the buffer will be filled is indicated by ahiac_Flags.
  471.           It is always filled with signed 16-bit (32 bit if AHIACB_HIFI in
  472.           in ahiac_Flags is set) words, even if playback is 8 bit. If
  473.           AHIDBB_STEREO is set (in ahiac_Flags), data for left and right
  474.           channel are interleaved:
  475.            1st sample left channel,
  476.            1st sample right channel,
  477.            2nd sample left channel,
  478.            ...,
  479.            ahiac_BuffSamples:th sample left channel,
  480.            ahiac_BuffSamples:th sample right channel.
  481.           If AHIDBB_STEREO is cleared, the mono data is stored:
  482.            1st sample,
  483.            2nd sample,
  484.            ...,
  485.            ahiac_BuffSamples:th sample.
  486.           Note that neither AHIACB_STEREO nor AHIACB_HIFI will be set if
  487.           you didn't report that you understand these flags when
  488.           AHI_AllocAudio() was called.
  489.  
  490.           For AHI V2, the type of buffer is also available in ahiac_BuffType.
  491.           It is suggested that you use this value instead. ahiac_BuffType
  492.           can be one of AHIST_M16S, AHIST_S16S, AHIST_M32S and AHIST_S32S.
  493.  
  494.        4) Convert the buffer if needed and feed it to the audio hardware.
  495.           Note that you may have to clear CPU caches if you are using DMA
  496.           to play the buffer, and the buffer is not allocated in non-
  497.           cachable RAM.
  498.  
  499.        5) [Call the ahiac_PostTimer function. A2 is assumed to point to
  500.           struct AHIAudioCtrlDrv. All registers are preserved.  (V4)]
  501.  
  502.        6) Wait until the whole buffer has been played, then repeat.
  503.  
  504.        Use double buffering if possible!
  505.  
  506.        You may DECREASE ahiac_BuffSamples slightly, for example to force an
  507.        even number of samples to be mixed. By doing this you will make
  508.        ahiac_PlayerFunc to be called at wrong frequency so be careful!
  509.        Even if ahiac_BuffSamples is defined ULONG, it will never be greater
  510.        than 65535.
  511.  
  512.        ahiac_BuffSize is the largest size of the mixing buffer that will be
  513.        needed until AHIsub_Stop() is called.
  514.  
  515.        ahiac_MaxBuffSamples is the maximum number of samples that will be
  516.        mixed (until AHIsub_Stop() is called). You can use this value if you
  517.        need to allocate DMA buffers.
  518.  
  519.        ahiac_MinBuffSamples is the minimum number of samples that will be
  520.        mixed. Most drivers will ignore it.
  521.  
  522.        If AHIsub_AllocAudio() returned with the AHISB_CANPOSTPROCESS bit set,
  523.        ahiac_BuffSize is large enough to hold two buffers. The mixing buffer
  524.        will be filled with the wet buffer first, immediately followed by the
  525.        dry buffer. I.e., ahiac_BuffSamples sample frames wet data, then
  526.        ahiac_BuffSamples sample frames dry data. The DSP fx should only be
  527.        applied to the wet buffer, and the two buffers should then be added
  528.        together. (V4)
  529.  
  530.      - If AHIsub_AllocAudio() returned AHISF_MIXING, do as described above,
  531.        except calling ahiac_PlayerFunc. ahiac_PlayerFunc should be called
  532.        ahiac_PlayerFreq times per second, clocked by timers on your sound
  533.        card or by using 'realtime.library'. No other Amiga resources may
  534.        be used for timing (like direct CIA timers).
  535.        ahiac_MinBuffSamples and ahiac_MaxBuffSamples are undefined if
  536.        AHIsub_AllocAudio() returned AHISF_MIXING (AHISB_TIMING bit not set).
  537.  
  538.      - If AHIsub_AllocAudio() returned with neither the AHISB_MIXING nor
  539.        the AHISB_TIMING bit set, then just start playback. Don't forget to
  540.        call ahiac_PlayerFunc ahiac_PlayerFreq times per second. Only your
  541.        own timing hardware or 'realtime.library' may be used. Note that
  542.        ahiac_MixerFunc, ahiac_BuffSamples, ahiac_MinBuffSamples,
  543.        ahiac_MaxBuffSamples and ahiac_BuffSize are undefined. ahiac_MixFreq
  544.        is the frequency the user wants to use for recording, if you support
  545.        that.
  546.  
  547.      * Second, assume bit AHISB_RECORD in flags is set. This means that you
  548.        should start to sample. Create a interrupt or task that does the
  549.        following:
  550.  
  551.        Allocate a buffer (you chose size, but try to keep it reasonable
  552.        small to avoid delays - it is suggested that RecordFunc is called
  553.        at least 4 times/second for the lowers sampling rate, and more often
  554.        for higher rates), and fill it with the sampled data. The buffer must
  555.        be long aligned, and it's size must be evenly divisible by four.
  556.        The format should always be AHIST_S16S (even with 8 bit mono samplers),
  557.        which means:
  558.            1st sample left channel,
  559.            1st sample right channel (same as prev. if mono),
  560.            2nd sample left channel,
  561.            ... etc.
  562.        Each sample is a signed word (WORD). The sample rate should be equal
  563.        to the mixing rate.
  564.  
  565.        Call the ahiac_SamplerFunc Hook with the following parameters:
  566.            A0 - (struct Hook *)           - The Hook itself
  567.            A2 - (struct AHIAudioCtrlDrv *)
  568.            A1 - (struct AHIRecordMessage *)
  569.        The message should be filled as follows:
  570.            ahirm_Type - Set to AHIST_S16S.
  571.            ahirm_Buffer - A pointer to the filled buffer.
  572.            ahirm_Samples - How many sample frames stored.
  573.        You must not destroy the buffer until next time the Hook is called.
  574.  
  575.        Repeat until AHIsub_Stop() is called.
  576.  
  577.      * Note that both bits may be set when this function is called.
  578.  
  579.  
  580. INPUTS
  581.        flags - See <libraries/ahi_sub.h>.
  582.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  583.  
  584.  
  585. RESULT
  586.        Returns AHIE_OK if successful, else an error code as defined
  587.        in <devices/ahi.h>. AHIsub_Stop() will always be called, even
  588.        if this call failed.
  589.  
  590.  
  591. NOTES
  592.        The driver must be able to handle multiple calls to this routine
  593.        without preceding calls to AHIsub_Stop().
  594.  
  595.  
  596. SEE ALSO
  597.        AHIsub_Update(), AHIsub_Stop()
  598.  
  599.  
  600. [driver].audio/AHIsub_Stop
  601.  
  602. NAME
  603.        AHIsub_Stop -- Stops playback.
  604.  
  605.  
  606. SYNOPSIS
  607.        AHIsub_Stop( flags, audioctrl );
  608.                     D0     A2
  609.  
  610.        void AHIsub_Stop( ULONG, struct AHIAudioCtrlDrv * );
  611.  
  612.  
  613. IMPLEMENTATION
  614.        Stop playback and/or recording, remove all resources allocated by
  615.        AHIsub_Start().
  616.  
  617.  
  618. INPUTS
  619.        flags - See <libraries/ahi_sub.h>.
  620.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  621.  
  622.  
  623. NOTES
  624.        It must be safe to call this routine even if AHIsub_Start() was never
  625.        called, failed or called more than once.
  626.  
  627.  
  628. SEE ALSO
  629.        AHIsub_Start()
  630.  
  631.  
  632. [driver].audio/AHIsub_Update
  633.  
  634. NAME
  635.        AHIsub_Update -- Update some variables
  636.  
  637.  
  638. SYNOPSIS
  639.        AHIsub_Update( flags, audioctrl );
  640.                       D0     A2
  641.  
  642.        void AHIsub_Update(ULONG, struct AHIAudioCtrlDrv * );
  643.  
  644.  
  645. IMPLEMENTATION
  646.        All you have to do is to update some variables:
  647.        Mixing & timing: ahiac_PlayerFunc, ahiac_MixerFunc, ahiac_SamplerFunc,
  648.        ahiac_BuffSamples (and perhaps ahiac_PlayerFreq if you use it).
  649.        Mixing only: ahiac_PlayerFunc, ahiac_MixerFunc, ahiac_SamplerFunc and
  650.            ahiac_PlayerFreq.
  651.        Nothing: ahiac_PlayerFunc, ahiac_SamplerFunc and ahiac_PlayerFreq.
  652.  
  653.  
  654. INPUTS
  655.        flags - Currently no flags defined.
  656.        audioctrl - pointer to an AHIAudioCtrlDrv structure.
  657.  
  658.  
  659. RESULT
  660.  
  661.  
  662. NOTES
  663.        This call must be safe from interrupts.
  664.  
  665.  
  666. SEE ALSO
  667.        AHIsub_Start()
  668.  
  669.  
  670.